To illustrate how to use an overlay window, Appendix C uses the routines described above to query the server for an overlay visual and then creates a normal plane window with a child in the overlay planes completely overlapping its parent. The background pixel value is set to a transparent pixel. Then like in the weather map example mentioned earlier, a semi-intricate black on white image is drawn in the normal planes while red text annotation is drawn in the overlay planes. Each time a mouse button is clicked, the overlay planes are cleared and the text is redrawn in a different position. The example demonstrates how the overlay planes can be modified without disturbing the image in the normal planes.
The example tries to find two appropriate visuals to use in making its ``layer sandwich.'' The code first looks at the default visual and tries to find a visual ``above'' it with transparency supported. If such a visual is not found, the code looks for a visual ``below'' the default visual to use but this requires that the default visual supports transparency. Note this strategy could fail to find an appropriate pair of visuals in some cases even when two potentially layerable visuals exist on a given server. The code is meant to be a relatively short, simple example to elucidate how to use layers in X; it is not meant to be a piece of production code.
The window created in the lower layer is the parent and the window created in the higher layer must be the child. It is important this ordering is not reversed. The layered transparency effect implies lower layers show through the transparent pixels of higher levels; not the other way around.
Because the overlay window is a child of the toplevel normal plane window, if we move the client's toplevel window, the overlay window moves too. Even though the windows are in different layers, the window hierarchy still dictates how windows move and interact.
Also consistent with the window hierarchy is the way events are distributed for overlay windows. In our example, the child covers the entire normal plane window so it receives all button clicks. Note that an overlay window receives mouse clicks even if the mouse is located on a transparent pixel. Transparency just affects how the pixel is displayed. Transparency does not affect the clipping region of a window. Similarly, if a transparent pixel is read from an overlay window using XGetImage the value read is not the displayed value but the transparent value for the pixel. So transparency does not change the value of the pixel in the window; it only affects the color displayed on the screen.
Appendix D presents one more simple example for a program called xlayerinfo that lists the visuals supported by a server including information about layering and transparency effects.